## Design decisions

**In-memory cache:** A scan with 20 findings of the same resource type
makes 1 NVD call, not 20.

**Keyword map is explicit:** Auto-generating search terms from resource
names produces noisy NVD results. The map in `cve_correlator.py` can be
extended as new rules are added — no other file needs to change.

**exploit_available uses CISA KEV:** The `cisaExploitAdd` field in NVD
responses flags a CVE as in CISA's Known Exploited Vulnerabilities
catalogue — more reliable than vendor-reported exploit status.

**Top-level cvss_score:** Returns the highest score across matched CVEs
so consumers don't need to iterate `cve_references` to find the worst case.

**Database migration is additive:** Uses `ALTER TABLE ... ADD COLUMN IF
NOT EXISTS` — safe to run against an existing database with findings.

Any rule with no mapping silently gets empty CVE results. That is not broken, but it is worth knowing.

---

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `cve_references` always `[]` | `rule_id` not in keyword map | Add it to `_RULE_CVE_KEYWORD_MAP` in `cve_correlator.py` |
| NVD calls in CI failing intermittently | Live API call in a test | Ensure all tests use `@patch("scanner.nvd_client.urllib.request.urlopen")` |
| `column cve_references does not exist` | Migration not run | Call `run_migrations()` in `create_app()` or run the `ALTER TABLE` manually |
| `cvss_score` is `None` for all findings | NVD returned CVEs with no metrics | Expected for older CVEs — check a specific CVE at nvd.nist.gov to confirm |
| 429 errors in logs during development | Too many manual test runs against NVD | Wait 30 seconds; the cache will prevent repeats within the same process |
| `exploit_available` always `False` | CVE not in CISA KEV | Correct — most CVEs are not in KEV; this is expected behaviour |
 
Closes #85